Uptime Kuma es probablemente el monitor de disponibilidad autoalojado más popular del panorama de código abierto. Aparecido en 2021 como proyecto personal de Louis Lam, ha crecido hasta tener más de 60.000 estrellas en GitHub, una comunidad activa y despliegues en producción en miles de organizaciones pequeñas y medianas. La versión 2.0 lanzada a principios de 2025 trajo cambios arquitectónicos importantes (migración a PostgreSQL opcional, interfaz rediseñada, soporte mejorado para monitores distribuidos) y consolidó el proyecto como alternativa seria a servicios de pago como UptimeRobot, Pingdom o Better Stack para equipos que prefieren autoalojarse. Esta guía cubre cómo instalarlo con Docker de forma razonable, configurar los monitores básicos, enchufar avisos a Telegram y Discord, y los errores operativos que es fácil cometer la primera vez.
Qué es Uptime Kuma y qué esperar
Uptime Kuma es una aplicación web escrita en Node.js que monitoriza disponibilidad de servicios mediante comprobaciones periódicas y notifica cuando detecta caídas. Soporta una variedad amplia de tipos de comprobación: HTTP y HTTPS con validación de código de respuesta y contenido del cuerpo, ping ICMP, puertos TCP abiertos, consultas DNS, consultas SQL contra bases de datos, endpoints gRPC, certificados SSL próximos a expirar, y una docena más. La interfaz web permite agrupar monitores, definir páginas de estado públicas y configurar más de noventa canales de avisos.
La propuesta pragmática del proyecto es llenar el hueco entre “montar Prometheus más Blackbox Exporter más Alertmanager con reglas a mano” y “pagar 50 euros al mes a UptimeRobot”. Para equipos con entre cinco y cien servicios que monitorizar, es la opción más razonable. La instalación lleva diez minutos, la configuración es visual sin YAML ni código, y un contenedor de 200 MB cubre todo el caso de uso sin más piezas.
Requisitos previos
Necesitas un servidor con Docker instalado. Cualquier distribución Linux reciente vale; yo recomiendo Debian 13 o Ubuntu 24.04 por estabilidad. El contenedor de Uptime Kuma consume poco: con 100 monitores activos usa aproximadamente 200 MB de RAM y menos del 5% de CPU de un núcleo. Cualquier VPS modesto (1 vCPU, 1 GB RAM) es suficiente.
El almacenamiento es importante. Uptime Kuma guarda todo el historial de comprobaciones en una base de datos (SQLite por defecto, PostgreSQL desde la 2.0). Con comprobaciones cada 60 segundos de 50 monitores, la base crece aproximadamente 100 MB al mes. Calcula un disco de al menos 10 GB pensado solo para Kuma si quieres conservar histórico largo.
Si vas a exponer Kuma a internet para ver el estado desde fuera, necesitas un dominio, un proxy inverso (nginx, Caddy o Traefik) y certificados SSL válidos. No expongas Kuma en HTTP plano ni dejes la interfaz accesible sin autenticación: es una aplicación con acceso a tu infraestructura interna y merece protección seria.
Instalación con Docker
La forma recomendada en 2025 es Docker Compose con un archivo de configuración pequeño:
services:
uptime-kuma:
image: louislam/uptime-kuma:1.23.16
container_name: uptime-kuma
restart: unless-stopped
volumes:
- ./data:/app/data
ports:
- "3001:3001"
environment:
- UPTIME_KUMA_PORT=3001
healthcheck:
test: ["CMD", "extra/healthcheck"]
interval: 60s
timeout: 30s
retries: 5
deploy:
resources:
limits:
memory: 512MGuarda esto como docker-compose.yml y levanta con docker compose up -d. Abre el navegador en http://tu-servidor:3001 y verás la pantalla de creación del usuario administrador. Elige un usuario y contraseña robustos; Uptime Kuma no tiene sistema de recuperación de contraseña directo y recuperar acceso requiere editar la base de datos manualmente.
Nota sobre la versión. La versión 1.23.x es la rama estable a finales de 2025; la 2.0 está disponible pero con algunos detalles todavía en movimiento. Para una instalación nueva de producción, la 1.23 es la opción conservadora. Si quieres probar la 2.0, hazlo en un entorno aparte primero y mide si los cambios de interfaz y base de datos te convienen.
Configuración inicial básica
Nada más entrar por primera vez conviene ajustar tres cosas. Primero, la zona horaria en Configuración → General; por defecto está en UTC y conviene configurarla a Europe/Madrid si operas desde aquí. Segundo, la autenticación de dos factores en Configuración → Seguridad con una aplicación compatible (Google Authenticator, Authy, 1Password): es una línea de defensa importante dado que Kuma mantiene credenciales sensibles para algunos tipos de monitor. Tercero, si Kuma está detrás de un proxy inverso, marca “Confiar en cabeceras de proxy” en General, sin lo cual las direcciones IP que registra son las del proxy y no las reales.
Crear los primeros monitores
La interfaz de creación de monitores es autoexplicativa pero hay decisiones importantes que vale la pena detallar. Para cada monitor conviene pensar en tres ejes: qué compruebo (endpoint), cada cuánto (intervalo) y qué considera fallo (condiciones).
Para sitios web públicos, la comprobación estándar es HTTP con intervalo de 60 segundos. Verifica al menos el código de respuesta y opcionalmente que el cuerpo contenga una cadena específica. Esto último es clave: un monitor que solo verifica código 200 no detecta cuando tu aplicación devuelve una página de error bonita con código 200. Para servicios internos expuestos por TCP, usa el tipo Port; para certificados SSL próximos a expirar, hay un tipo específico que conviene configurar con umbral de 21 días.
Agrupa los monitores en etiquetas coherentes por criticidad (crítico, importante, informativo) y por sistema. Así puedes filtrar en paneles y dirigir avisos distintos a canales distintos según gravedad.
Configurar avisos a Telegram
Telegram es uno de los canales de aviso más cómodos. Crea un bot hablando con @BotFather en Telegram, sigue las instrucciones y apunta el token que te da. Después necesitas el identificador del chat donde quieres recibir avisos. Para un chat personal, abre una conversación con el bot y envíale /start, luego consulta https://api.telegram.org/bot<TU_TOKEN>/getUpdates en el navegador para ver el identificador. Para un grupo, añade el bot al grupo y haz el mismo truco.
En Uptime Kuma, ve a Configuración → Notificaciones → Añadir. Selecciona Telegram, pega el token y el identificador de chat, y prueba con el botón “Probar”. Si todo está bien, recibirás un mensaje de prueba. Después, asigna esta notificación a los monitores que quieras. Hazlo preferiblemente desde las etiquetas de grupo, no monitor por monitor, para mantener la configuración manejable.
Configurar avisos a Discord
Discord usa webhooks entrantes. En tu servidor de Discord, ve a ajustes del canal → Integraciones → Webhooks → Nuevo webhook. Copia la URL del webhook. En Uptime Kuma, Notificaciones → Añadir → Discord, pega la URL y elige nombre y avatar opcionales. Prueba y asigna a los monitores deseados.
Hay un detalle que conviene conocer. Discord limita la frecuencia de mensajes por webhook (aproximadamente 30 por minuto con picos permitidos). Si tienes 100 monitores y todos fallan a la vez por un corte de red en el servidor de Kuma, Discord puede empezar a rechazar mensajes y perderás avisos. Para producción seria con muchos monitores, considera agrupar avisos por ventana de tiempo usando un intermediario como ntfy.sh o un servicio de guardia dedicado.
Página de estado pública
Una característica útil es la página de estado pública, donde puedes mostrar el estado de servicios seleccionados a usuarios externos sin darles acceso al panel completo. En el menú lateral, entra en Páginas de Estado → Añadir Nueva. Elige qué monitores mostrar, el tema, el dominio (si lo expones en tu propio dominio), y publica.
La práctica recomendada es tener al menos dos páginas: una pública con los servicios cara al usuario, y una interna con todos los monitores incluyendo los internos. Esto te permite comunicar estado a clientes sin revelar detalles de tu infraestructura.
Errores frecuentes que evitar
El primero es no configurar backup. Uptime Kuma guarda todo en /app/data; si ese volumen se pierde, pierdes toda la configuración y el historial. Programa una copia diaria del directorio de datos a otra ubicación con un cron sencillo.
El segundo es dejar la interfaz expuesta sin HTTPS ni autenticación fuerte. Kuma gestiona credenciales sensibles (tokens de avisos, cadenas de conexión, URLs internas). Exponerla con un admin con contraseña débil es regalar una entrada a tu infraestructura.
El tercero es no validar los avisos. Tras configurar Telegram o Discord, prueba con un monitor artificial que caiga a propósito para confirmar que el aviso llega. No confíes en que está funcionando porque vio el mensaje de prueba; el flujo real “monitor falla, aviso sale” tiene más piezas y puede romperse en puntos distintos. El cuarto es poner intervalos demasiado agresivos: 10 segundos para 100 monitores genera mucha carga; 60 segundos es razonable para la mayoría de casos.
Cómo pensar la decisión
Uptime Kuma es una herramienta notablemente bien hecha para un problema acotado, y esa es su fortaleza. No intenta ser Grafana, no intenta ser Prometheus con reglas complejas, no gestiona métricas de aplicación. Hace una cosa (comprobar si tus cosas están vivas y avisarte si no) y la hace con simpleza suficiente para que un equipo pequeño la mantenga sin dedicar tiempo significativo.
Para un equipo que acaba de entrar en monitorización seria, Uptime Kuma es probablemente la mejor primera pieza a instalar antes que nada más. Te da cobertura básica inmediata, te enseña disciplina de pensar qué merece ser monitorizado, y cuando llegue el momento de añadir observabilidad más profunda con Prometheus o con una pila completa, Kuma seguirá cubriendo su capa sin interferir. Es una herramienta que no compite con nada más; simplemente hace su trabajo y desaparece del radar hasta que algo falla, que es exactamente lo que se le pide a un monitor de disponibilidad.
